My Profile_

Overview

The Moneris Hosted Tokenization (HT) was designed as a solution for online e-commerce merchants that do not wish to handle credit card numbers directly on their websites but want to have the ability to fully customize their checkout page appearance. When a HT transaction is initiated, the Moneris Gateway will present and display on the merchant’s behalf, a single text box on the checkout page. The cardholder can then securely enter their credit card information into the text box. Upon submission of the payment information on the check out page the Moneris Gateway will return a temporary token representing the credit card number to the merchant. This token would then be used in an API call to process a financial transaction directly with Moneris to charge the card. Upon receiving a response to the financial transaction, the merchant would then generate a receipt and allow the cardholder to continue on with the online shopping experience.

Hosted Tokenization Setup Steps

Hosted Tokenization – You will need to follow these steps.

  1. Login to your Moneris Gateway Merchant Resource Centre:
  2. Click on ‘Admin on the menu.
  3. Click on ‘Hosted Tokenization’ in the sub-menu.
  4. Enter the source domain page. This is the address of the main outer page that sends the transaction to Moneris.
  5. Click the button “Create Profile”
  6. Make a note of the Profile ID that gets generated since this will need to be included in your HTML iFrame code.
  7. Do the required development as outlined here
  8. Test your solution in the test environment
  9. Activate your production store
  10. Create and configure your product Hosted Tokenization store in the production Merchant Resource Centre
  11. Make the necessary changes to move your solution from the test environment into production

Getting a Temporary Token

To get a temporary token you will need to send a request to Moneris from within an IFrame. A sample code is illustrated below. Note that the Profile ID in the HTML link below will need to be replaced with your own Profile ID, which you can configure the MRC as described here.  Also, the src and postMessage URL will need to be updated to the appropriate QA or production URL listed in the table below.

Canada
QA https://esqa.moneris.com/HPPtoken/index.php    
Production https://www3.moneris.com/HPPtoken/index.php

Canada Code Sample

<html>
<head>
                <title> Outer Frame - Merchant Page</title>

                <script>

                                function doMonerisSubmit()
                                {
                                                var monFrameRef = document.getElementById('monerisFrame').contentWindow;
                                                monFrameRef.postMessage('tokenize','https://esqa.moneris.com/HPPtoken/index.php');
//change link according to table above 
                                                return false;
                                }

                                var respMsg = function(e) 
                                {
                                                var respData = eval("(" + e.data + ")");
                                                document.getElementById("monerisResponse").innerHTML = e.origin + " SENT " + " - " +
respData.responseCode + "-" + respData.dataKey + "-" + respData.errorMessage;
                                                document.getElementById("monerisFrame").style.display = 'none';
                                }

                                window.onload = function() 
                                {
                                                if (window.addEventListener) 
                                                {  
                                                                window.addEventListener ("message", respMsg, false);
                                                }
                                                else 
                                                {
                                                                if (window.attachEvent) 
                                                                {   
                                                                window.attachEvent("onmessage", respMsg);
                                                                }
                                                }
                                }
                </script>
</head>
<body>

<div>This is the outer page</div>

<div id=monerisResponse></div>

<iframe id=monerisFrame src=https://esqa.moneris.com/HPPtoken/index.php?id=htFTMQ8J63EYNZS&pmmsg=true&css_body=background:green;&css_textbox=border-width:2px;&css_textbox_pan=width:140px;&enable_exp=1&css_textbox_exp=width:40px;&enable_cvd=1&css_textbox_cvd=width:40px&enable_exp_formatting=1&enable_cc_formatting=1 frameborder='0' width="200px" height="200px"></iframe>

 

<input type=button onClick=doMonerisSubmit() value="submit iframe">

</body>
</html>

Mandatory Variables

Variable Name

Definition

Id

Required - Provided by the Hosted Tokenization profile configuration tool in the MRC.

css_body

Required - CSS applied to the body.  By default margin and padding is set to 0.

css_textbox

Required - CSS applied to all text boxes in general.

 

Optional variables

Variable Name

Definition

pmmsg

Recommended - Forces form to only accept message of 'tokenize'.

css_textbox_pan

Optional - CSS applied to the pan text box specifically.

enable_exp

Optional - Must be set to 1 for expiry date text box to be displayed (Format: MMYY)

css_textbox_exp

Optional - CSS applied to the expiry date text box specifically.

enable_cvd

Optional - Must be set to 1 for CVD text box to be displayed

css_textbox_cvd

Optional - CSS applied to the CVD text box specifically.

display_labels

Optional – 0 for no labels, 1 for traditional labels, 2 for place holder labels.

css_input_label

Optional – CSS for input labels

css_label_pan

Optional – CSS for card number label

css_label_exp

Optional – CSS for expiry date label

css_label_cvd

Optional – CSS for CVD label

pan_label

Optional – text for card number label (default is “Card Number”)

exp_label

Optional – text for expiry date label (default is “Expiry Date”)

cvd_label

Optional – text for CVD label (default is “CVD”)

enable_exp_formatting

Optional - Formatting applied to expiry date field to display a slash between month and year (Format: MM/YY). Must be set to 1 to enable formatting.

enable_cc_formatting

Optional - Formatting applied to credit card number based on the card type (Format: Visa - 4242 4242 4242 4242, MC - 5454 5454 5454 5454, Amex - 333 666666 55555)

 

Response Fields

The response will be returned as JSON.  It will contain 4 arguments:

responseCode

Indication whether the page-loading or card-submission was successful or why it failed.  Please note, if expiry text box or CVD text box are enabled, the returned responseCode value will be in the form of a list (e.g. [“944”,”943”]), since there may be more than one failure.  For example, in the case where both the card number entered and expiry date are invalid.  If only the card number text box is displayed, the responseCode will be returned in the form of a string.

errorMessage

Description of failure (This is a very generic description – see “responseCode Definitions” below for specific error code results).

bin

BIN range of the submitted card number.  Provides merchant ability to determine the card type and perform any card-specific processing.

dataKey

Tokenized card number.  This is what is used with the Vault API transaction

Response Code Definitions

001

Successful creation of temporary token

940

Invalid profile id (on tokenization request)

941

Error generating token

942

Invalid Profile ID, or source URL

943

Card data is invalid (not numeric, fails mod10, we will remove spaces)

944

Invalid expiration date (mmyy, must be current month or in the future)

945

Invalid CVD data (not 3-4 digits)

 


Forwarding a temporary token to your payment processing page

This section describes how to receive the response from the Hosted Tokenization page containing the temporary token. 


Canada Code Sample

var respMsg = function(e) 
{
                                    var respData = eval("(" + e.data + ")");
                                    document.getElementById("monerisResponse").innerHTML = e.origin + " SENT " + " - " + respData.responseCode + "-" + respData.dataKey + "-" + respData.errorMessage;
                                    document.getElementById("monerisFrame").style.display = 'none';
// your token will be in the field: respData.dataKey
// from this point in the Javascript you can have more code that posts the token to another page that will actually process the payment.
}

Processing The Payment

To charge the card using the temporary token you will need to send the temporary token to a page on your site that implements the Moneris Vault API.

For more details on the Vault API please refer to VAULT API. The following are examples of transactions that can be performed with your token:

    • Purchase with Vault (API | Batch)
    • Pre-Authorization with Vault (API | Batch)
    • Card Verification with Vault (API)
    • Vault Add Token (API)